Aminet 3/Aminet 3 - July 1994.iso/Aminet/dev/e/StdErr.lha/StdErr/StdErr.DOC

Text File | 1994-04-09 | 9.4 KB | 265 lines

Document StdErr

StdErr.E is a product of the Cheese Olfactory Workshop.  Eat your greens.

0. Distributability
-------------------

If you were able to get this, you may use it.  If you are willing to
distribute it FREE OF CHARGE, by all means distribute it.  I would ask,
for the sake of following your own conscience, that if you MUST charge
someone money for this, that you not charge more than DevCon would charge
for their PD disks (roughly $5 US or less a disk).

1. Usage
--------

Very simple, really.. all depending on your needs.

First thing to remember, however, is that you must err_Dispose() by the
end of your program (or, at LEAST err_Close().. but err_Dispose() is the
recommended method to use).  If you fail to do this, you will leave a
filehandle open (possibly), which would be very bad... it could also waste
memory to do so.

The next thing to remember is that StdErr.E really works best with EPP.
EPP can make your life very easy.  It's truly a remarkable program.  If
you're an E programmer working without EPP, you're making your life more
difficult than necessary.  Insure you download the very latest version of
this useful utility by Barry Wills.  Amusingly, I did not use EPP to
write StdErr.E.

Otherwise...

1.1. stderr.filename
--------------------

If you want to change where your error messages are sent, you may reassign
stderr.filename wherever you want the messages to go.  For example:

stderr.filename:='RAM:error.txt'

will cause it to be appended to a file called 'error.txt' in the RAM:
(yes, StdErr.E automatically appends messages to files, rather than
overwriting the file).

stderr.filename:=stdout

will direct error messages to the stdout filehandler.  It is the only case
where a filehandler may be used instead of a string.

stderr.filename:='CONSOLE:'

will direct error messages to the stderr port (like C does).  That is, if
run from a shell, it'll print its messages to the shell, rather than to
any potentially redirected output (eg. if someone typed 'command >moo.txt'
the errors would not go into moo.txt, but to the console instead).

1.2. err_New(filename)
----------------------

VOID err_New(LONG filename)

err_New() takes one argument, a string pointer (?) that will be inserted as
the filename for the stderr port.

err_New() does NOT open a file.. it only allocates storage for the stderr
port.  It is intended to be used if the stderr port is to be initialized
to a particular area prior to writing any error messages (that is, you
already know you want your error messages to go to, say, 'ram:boo.bob', so
you use err_New('ram:boo.bob') to prepare the program to do so).

You may want to read `stderr.filename' for more information.

1.3. err_Close()
----------------

VOID err_Close(VOID)

err_Close() takes no arguments... in fact, you should really avoid using
it.  If E were C++, I would have hidden this as a private method.  As it
is, you COULD use it, but I don't recommend it.

But, for the curious, err_Close() will close the filehandle (if it is safe
to do so).

I would STRONGLY recommend using `err_Dispose()' instead of this command.

1.4. err_Dispose()
------------------

VOID err_Dispose(VOID)

This command will safely close the filehandle used by `err_Close()', and
Dispose() of all bits of memory allocated earlier.  You really should use
this command at the end of your application, just before exiting, in order
to safely close the filehandle and Dispose() allocated memory (although E
will do the deallocating of memory automatically, I try to be a clean
programmer).

Remember.. before your ENDPROC main(), err_Dispose().

1.5. err_Open()
---------------

VOID err_Open(VOID)

You should NEVER call this procedure.

The only thing you might consider doing to this procedure is modifying the
format string appearing DEEP in a VfPrintf() statement that displays the
date, time, and weekday as a sort of file-header.. you might want to
change the word 'ERROR:' to the name of your program or something.

Otherwise, basically, this procedure opens a filehandler for stderr
(making sure it can do so legally).  It does a lot of checking and
fool-proofing, allowing you to change `stderr.filename' easily.  It also
closes filehandles if you've changed stderr.filename.  It's a fairly smart
procedure.  If any bugs exist in it, please let me know.

1.6. err_WriteF(format,items)
-----------------------------

VOID err_WriteF(LONG format, LONG items)

format - a bit of text to be printed out, similiar to WriteF(), but
          without '\s' statements.
items  - a list of numbers that you may wish to have printed according to
          the format above.

Basically, this is the procedure you use to write your error messages.

Simply speaking, this statement works very similiarly to WriteF(), except
that you cannot format strings, and the numbers you might format have to
be in an E-list format (eg. [12,234,15,6]).  So, you must use it like:

err_WriteF('MyProg: \d cols is not enough!\nNeither is \d lines!\n',
           [col,lines])

If col = 5 and lines = 2, then the above should print:

               MyProg: 5 cols is not enough!
               Neither is 2 lines!

err_WriteF() will call `err_Open()', insuring it has a place to write
information into.

1.7. Possible Problems
----------------------

StdErr should generally work fairly well, but since it needs to allocate
memory, and it needs to open files, there always exists the possibility
that it will fail.

StdErr has been designed to be as careful of these matters as possible, but
I strongly recommend any programmer using StdErr to use RAISE IF statements
(with Open and New) to protect his/her program from inexplicable errors.
StdErr has been designed with error handling in these matters, with text
being written via WriteF() (a most reliable way to write information)
should it fail.

Use of the StdErrExample.E as a guide is recommended.

1.8. General Pattern of Use
---------------------------

Basically, use PMODULE 'PMODULE:StdErr' in your program, then invoke
it something like:

PROC main()

 DEF ...
 err_New(NIL) /* stderr, as in C */

 blah blah blah

 err_WriteF('You are missing line #\d',[line]) /* error message */

 blah blah blah

 err_Dispose()

ENDPROC

2. About The Author
-------------------

I'm surprised you care!

My name is Joseph Edwards Van Riper III (although I'm generally called
'Trey').  I have written another program called 'Quip', which is a fortune
cookie program that will eat your brain ... it has more features than any
other fortune cookie program in existence.  A dubious honour, authoring
that monster.  I've uploaded two datafiles for that program.. QuipZen and
QuipMusic.

Currently, I am a junior at the University of North Carolina, Asheville,
working towards my Bachelor of Arts in Music (with an emphasis on
Composition).  I have one more year left here, and it would appear that I
will finish with my degree in that year, totally four years of college
life for me (a shorter time than some of my companions, I've noticed).

I was in the US Army as a bandsman/journalist for five years and a month,
two years of which I spent in Japan (Camp Zama, for the curious).  I would
care not to repeat that experience.

I type blindingly fast for a non-clerical student, and I work with
computers with an intuitive feel for them; when something goes wrong, I
can intuitively sense where the problem is, and find a solution.

I think computers will steal my soul if I'm not careful.

I am a vegetarian (vegan, and becoming even stricter in my eating
practices), and a non-denominational Christian.

You may mail me at [e-mail].  If you can find the Mosaic
server at UNCA, you can poll my account for MIDI specs and more junk about
myself.  You can also find me lurking around the Amiga E mailing list.

Moo.

3. About The Program
--------------------

StdErr.E was originally an idea born inside Quip.E (that is, Quip the
Fortune Cookie Program from Hell, not the QWK reader).

I was having a horrible time handling my error messages.  I had some very
specific needs, considering icons and stuff.  I worked out all my problems
with Quip, finally getting something to work the way I wanted it to do.

Then I realized that there may be others who needed something similar to
Quip's stderr handling, although reading through Quip.E to find the
necessary bits of code would require someone with more patience than Job.
I thought, therefore, I should extract the core of my routines, re-form
them to be simpler to use, and add a few extra nifty features.

Thus, StdErr.E was born.

StdErr, being reworked from Quip's stderr handling, works better, and is
far more organized.  I attempted to follow an Object Oriented approach,
despite the fact that Amiga E is not an Object Oriented language.  To this
end, I used the 'err_' prefix, while using fairly common commands such as
'WriteF' and 'Open' to keep things organized and simple to understand in
function.  I also created an Object, and purposely renamed one of the
members in the object a value that wouldn't have as much meaning to
people, since I didn't want anyone messing with it.

I decided to use 'stderr' as a global variable, because essentially nobody
else should have a need for such a variable name, once these methods are
employed, and it seemed to be a very easy variable name to remember.

StdErr.E has been tested, and should not leak memory or crash.  It tries
to be very durable.

4. To Do
--------

The only things I can think of that would really improve this code
tremendously would be:

* Allow strings to be formatted in the text.

* Include Fault() handling as an option.